package com.example.rssreader.service;

import com.example.rssreader.common.PageResponse;
import com.example.rssreader.dto.AddFeedRequest;
import com.example.rssreader.dto.FeedResponse;
import com.example.rssreader.entity.RssFeed;

import java.util.List;

/**
 * RSS源服务接口
 * 定义RSS源相关的业务操作
 * 
 * @author RSS Reader Team
 * @version 1.0.0
 * @since 2024-01-01
 */
public interface RssFeedService {

    /**
     * 添加RSS源
     * 验证URL有效性，解析RSS源信息并保存
     * 
     * @param request 添加RSS源请求参数
     * @return RSS源响应信息
     * @throws RuntimeException 当RSS源URL无效或已存在时抛出异常
     */
    FeedResponse addFeed(AddFeedRequest request);

    /**
     * 分页查询RSS源列表
     * 
     * @param page 页码，从1开始
     * @param size 每页大小
     * @return 分页响应结果
     */
    PageResponse<FeedResponse> getFeeds(Integer page, Integer size);

    /**
     * 根据ID获取RSS源详情
     * 
     * @param id RSS源ID
     * @return RSS源响应信息
     * @throws RuntimeException 当RSS源不存在时抛出异常
     */
    FeedResponse getFeedById(Long id);

    /**
     * 更新RSS源信息
     * 只允许更新标题和描述
     * 
     * @param id          RSS源ID
     * @param title       新标题
     * @param description 新描述
     * @return 更新后的RSS源响应信息
     * @throws RuntimeException 当RSS源不存在时抛出异常
     */
    FeedResponse updateFeed(Long id, String title, String description);

    /**
     * 删除RSS源
     * 逻辑删除，同时删除该RSS源下的所有文章
     * 
     * @param id RSS源ID
     * @throws RuntimeException 当RSS源不存在时抛出异常
     */
    void deleteFeed(Long id);

    /**
     * 手动同步RSS源
     * 立即抓取指定RSS源的最新文章
     * 
     * @param id RSS源ID
     * @return 同步结果信息
     * @throws RuntimeException 当RSS源不存在或同步失败时抛出异常
     */
    String syncFeed(Long id);

    /**
     * 搜索RSS源
     * 根据关键词在标题和描述中进行模糊搜索
     * 
     * @param keyword 搜索关键词
     * @param page    页码，从1开始
     * @param size    每页大小
     * @return 分页响应结果
     */
    PageResponse<FeedResponse> searchFeeds(String keyword, Integer page, Integer size);

    /**
     * 获取所有活跃的RSS源
     * 用于定时同步任务
     * 
     * @return RSS源实体列表
     */
    List<RssFeed> getAllActiveFeeds();

    /**
     * 同步所有RSS源
     * 定时任务调用，批量同步所有RSS源的最新文章
     * 
     * @return 同步结果统计信息
     */
    String syncAllFeeds();

    /**
     * 验证RSS源URL
     * 检查URL是否可访问且为有效的RSS格式
     * 
     * @param url RSS源URL
     * @return 验证结果信息
     */
    String validateFeedUrl(String url);

    /**
     * 获取RSS源统计信息
     * 
     * @return 统计信息，包括总数、最近更新数量等
     */
    Object getFeedStatistics();
}